home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 January: Mac OS SDK / Dev.CD Jan 98 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / AIncludes / Translation.a < prev    next >
Encoding:
Text File  |  1997-08-12  |  12.7 KB  |  354 lines  |  [TEXT/MPS ]
  1. ;
  2. ;    File:        Translation.a
  3. ;
  4. ;    Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5. ;
  6. ;    Version:    Technology:    Macintosh Easy Open 1.1
  7. ;                Release:    Universal Interfaces 3.0.1
  8. ;
  9. ;    Copyright:    © 1991-1997 by Apple Computer, Inc., all rights reserved.
  10. ;
  11. ;    Bugs?:        Please include the the file and version information (from above) with
  12. ;                the problem description.  Developers belonging to one of the Apple
  13. ;                developer programs can submit bug reports to:
  14. ;
  15. ;                    devsupport@apple.com
  16. ;
  17. ;
  18.     IF &TYPE('__TRANSLATION__') = 'UNDEFINED' THEN
  19. __TRANSLATION__ SET 1
  20.  
  21.     IF &TYPE('__TYPES__') = 'UNDEFINED' THEN
  22.     include 'Types.a'
  23.     ENDIF
  24.     IF &TYPE('__FILES__') = 'UNDEFINED' THEN
  25.     include 'Files.a'
  26.     ENDIF
  27.     IF &TYPE('__COMPONENTS__') = 'UNDEFINED' THEN
  28.     include 'Components.a'
  29.     ENDIF
  30.     IF &TYPE('__TRANSLATIONEXTENSIONS__') = 'UNDEFINED' THEN
  31.     include 'TranslationExtensions.a'
  32.     ENDIF
  33.  
  34. ;  enumerated types on how a document can be opened
  35. ; typedef short                         DocOpenMethod
  36.  
  37.  
  38. domCannot                        EQU        0
  39. domNative                        EQU        1
  40. domTranslateFirst                EQU        2
  41. domWildcard                        EQU        3
  42. ;  0L terminated array of OSTypes, or FileTypes
  43. TypesBlock                RECORD 0
  44. elements                 ds.l    64
  45. sizeof                     EQU *                    ; size:   $100 (256)
  46.                         ENDR
  47.  
  48.  
  49. ; typedef OSType *                        TypesBlockPtr
  50.  
  51. ;  Progress dialog resource ID
  52.  
  53. kTranslationScrapProgressDialogID EQU    -16555
  54. ;  block of data that describes how to translate
  55. FileTranslationSpec        RECORD 0
  56. componentSignature         ds.l    1                ; offset: $0 (0)
  57. translationSystemInfo     ds.l    1                ; offset: $4 (4)
  58. src                         ds        FileTypeSpec    ; offset: $8 (8)
  59. dst                         ds        FileTypeSpec    ; offset: $1C (28)
  60. sizeof                     EQU *                    ; size:   $30 (48)
  61.                         ENDR
  62. ; typedef struct FileTranslationSpec *    FileTranslationSpecArrayPtr
  63.  
  64. ; *****************************************************************************************
  65. ;* 
  66. ;*   GetFileTypesThatAppCanNativelyOpen
  67. ;* 
  68. ;*  This routine returns a list of all FileTypes that an application can open by itself
  69. ;* 
  70. ;*  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  71. ;*             appSignature        signature (creator) of application
  72. ;*             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  73. ;* 
  74. ;*  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  75. ;
  76.  
  77. ;
  78. ; pascal OSErr GetFileTypesThatAppCanNativelyOpen(short appVRefNumHint, OSType appSignature, FileType *nativeTypes)
  79. ;
  80.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  81.         Macro
  82.         _GetFileTypesThatAppCanNativelyOpen
  83.             moveq               #28,D0
  84.             dc.w                $ABFC
  85.         EndM
  86.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  87.         IMPORT_CFM_FUNCTION GetFileTypesThatAppCanNativelyOpen
  88.     ENDIF
  89.  
  90. ; *****************************************************************************************
  91. ;* 
  92. ;*  ExtendFileTypeList
  93. ;* 
  94. ;*  This routine makes a new list of file types that can be translated into a type in the given list
  95. ;*  Used by StandardFile
  96. ;* 
  97. ;*  Enter:    originalTypeList        pointer to list of file types that can be opened
  98. ;*             numberOriginalTypes        number of file types in orgTypeList
  99. ;*              extendedTypeList        pointer to a buffer to be filled with file types
  100. ;*             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  101. ;* 
  102. ;*  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  103. ;*             numberExtendedTypes        number of file types put in extendedTypeList
  104. ;
  105.  
  106. ;
  107. ; pascal OSErr ExtendFileTypeList(const FileType *originalTypeList, short numberOriginalTypes, FileType *extendedTypeList, short *numberExtendedTypes)
  108. ;
  109.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  110.         Macro
  111.         _ExtendFileTypeList
  112.             moveq               #9,D0
  113.             dc.w                $ABFC
  114.         EndM
  115.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  116.         IMPORT_CFM_FUNCTION ExtendFileTypeList
  117.     ENDIF
  118.  
  119.  
  120. ; *****************************************************************************************
  121. ;* 
  122. ;* 
  123. ;*  This routine checks if a file can be opened by a particular application.
  124. ;*  If so, it returns if it needs to be translated first, and if so then how.
  125. ;*  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  126. ;*  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  127. ;* 
  128. ;*  Enter:    targetDocument        document to check if it can be opened
  129. ;*             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  130. ;*             appSignature        signature (creator) of application to open doc
  131. ;*             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  132. ;*             onlyNative            whether to consider if document can be translated before opening
  133. ;*             howToOpen            pointer to buffer in which to put how the document can be opened
  134. ;*             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  135. ;* 
  136. ;*  Exit:    howToOpen            whether file needs to be translated to be read
  137. ;*             howToTranslate        if file can be translated, buffer filled in with how to translate
  138. ;*             returns                noErr, noPrefAppErr
  139. ;
  140.  
  141. ;
  142. ; pascal OSErr CanDocBeOpened(const FSSpec *targetDocument, short appVRefNumHint, OSType appSignature, const FileType *nativeTypes, Boolean onlyNative, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  143. ;
  144.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  145.         Macro
  146.         _CanDocBeOpened
  147.             moveq               #30,D0
  148.             dc.w                $ABFC
  149.         EndM
  150.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  151.         IMPORT_CFM_FUNCTION CanDocBeOpened
  152.     ENDIF
  153.  
  154.  
  155. ; *****************************************************************************************
  156. ;* 
  157. ;*  GetFileTranslationPaths
  158. ;* 
  159. ;*  This routine returns a list of all ways a translation can occure to or from a FileType.
  160. ;*  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  161. ;* 
  162. ;*  Enter:    srcDoc            source file or NULL for all matches
  163. ;*             dstDoc            destination FileType or NULL for all matches
  164. ;*             maxResultCount
  165. ;*             resultBuffer
  166. ;*  Exit:    number of paths
  167. ;
  168.  
  169. ;
  170. ; pascal short GetFileTranslationPaths(FSSpec *srcDocument, FileType dstDocType, unsigned short maxResultCount, FileTranslationSpecArrayPtr resultBuffer)
  171. ;
  172.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  173.         Macro
  174.         _GetFileTranslationPaths
  175.             moveq               #56,D0
  176.             dc.w                $ABFC
  177.         EndM
  178.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  179.         IMPORT_CFM_FUNCTION GetFileTranslationPaths
  180.     ENDIF
  181.  
  182. ; *****************************************************************************************
  183. ;* 
  184. ;*  GetPathFromTranslationDialog
  185. ;* 
  186. ;*  This routine, with a given document, application, and a passed typelist will display the
  187. ;*  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  188. ;*  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  189. ;*  The routine returns the translation path information.
  190. ;* 
  191. ;*  Enter:    theDocument            FSSpec to document to open
  192. ;*             theApplication        FSSpec to application to open document
  193. ;*             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  194. ;*                                 you would like the documented translated to.  Order most perferred
  195. ;*                                 to least.
  196. ;* 
  197. ;*  Exit:    howToOpen            Translation method needed to open document
  198. ;*             howToTranslate        Translation specification
  199. ;*             returns                Any errors that might occur.
  200. ;
  201.  
  202. ;
  203. ; pascal OSErr GetPathFromTranslationDialog(const FSSpec *theDocument, const FSSpec *theApplication, TypesBlockPtr typeList, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  204. ;
  205.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  206.         Macro
  207.         _GetPathFromTranslationDialog
  208.             moveq               #55,D0
  209.             dc.w                $ABFC
  210.         EndM
  211.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  212.         IMPORT_CFM_FUNCTION GetPathFromTranslationDialog
  213.     ENDIF
  214.  
  215.  
  216. ; *****************************************************************************************
  217. ;* 
  218. ;*   TranslateFile
  219. ;* 
  220. ;*  This routine reads a file of one format and writes it to another file in another format. 
  221. ;*  The information on how to translated is generated by the routine CanDocBeOpened.
  222. ;*  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  223. ;*  The destination file must not exist.  It is created by this routine.  
  224. ;* 
  225. ;*  Enter:    sourceDocument            input file to translate
  226. ;*             destinationDocument        output file of translation
  227. ;*             howToTranslate            pointer to info on how to translate
  228. ;*  Exit:    returns                    noErr, badTranslationSpecErr 
  229. ;
  230.  
  231. ;
  232. ; pascal OSErr TranslateFile(const FSSpec *sourceDocument, const FSSpec *destinationDocument, const FileTranslationSpec *howToTranslate)
  233. ;
  234.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  235.         Macro
  236.         _TranslateFile
  237.             moveq               #12,D0
  238.             dc.w                $ABFC
  239.         EndM
  240.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  241.         IMPORT_CFM_FUNCTION TranslateFile
  242.     ENDIF
  243.  
  244. ; *****************************************************************************************
  245. ;* 
  246. ;*   GetDocumentKindString
  247. ;* 
  248. ;*  This routine returns the string the Finder should show for the "kind" of a document
  249. ;*  in the GetInfo window and in the kind column of a list view.  
  250. ;* 
  251. ;*  Enter:    docVRefNum        The volume containing the document
  252. ;*             docType            The catInfo.fdType of the document
  253. ;*             docCreator        The catInfo.fdCreator of the document
  254. ;*             kindString        pointer to where to return the string
  255. ;* 
  256. ;*  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  257. ;*             returns            noErr, or afpItemNoFound if kind could not be determined
  258. ;
  259.  
  260. ;
  261. ; pascal OSErr GetDocumentKindString(short docVRefNum, OSType docType, OSType docCreator, Str63 kindString)
  262. ;
  263.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  264.         Macro
  265.         _GetDocumentKindString
  266.             moveq               #22,D0
  267.             dc.w                $ABFC
  268.         EndM
  269.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  270.         IMPORT_CFM_FUNCTION GetDocumentKindString
  271.     ENDIF
  272.  
  273. ; *****************************************************************************************
  274. ;* 
  275. ;*  GetTranslationExtensionName
  276. ;* 
  277. ;*  This routine returns the translation system name from a specified TranslationSpec
  278. ;* 
  279. ;*  Enter:    translationMethod    The translation path to get the translation name from
  280. ;* 
  281. ;*  Exit:    extensionName        The name of the translation system
  282. ;*             returns                Any errors that might occur
  283. ;
  284.  
  285. ;
  286. ; pascal OSErr GetTranslationExtensionName(const FileTranslationSpec *translationMethod, Str31 extensionName)
  287. ;
  288.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  289.         Macro
  290.         _GetTranslationExtensionName
  291.             moveq               #54,D0
  292.             dc.w                $ABFC
  293.         EndM
  294.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  295.         IMPORT_CFM_FUNCTION GetTranslationExtensionName
  296.     ENDIF
  297.  
  298.  
  299. ; *****************************************************************************************
  300. ;* 
  301. ;*  GetScrapDataProcPtr
  302. ;* 
  303. ;*  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  304. ;*  get the data to be translated.  The first call TranslateScrap will make to this is to
  305. ;*  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  306. ;*  with a list all the formats that you have available to be translated, and the length of each.
  307. ;*  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  308. ;*  the formats that 'fmts' list said was available.
  309. ;* 
  310. ;*  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  311. ;*             dataH                    Handle in which to put the requested data
  312. ;*             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  313. ;*             
  314. ;*  Exit:    dataH                    Handle is resized and filled with data in requested format
  315. ;
  316.  
  317. ; typedef GetScrapDataUPP                 GetScrapData
  318.  
  319. ; *****************************************************************************************
  320. ;* 
  321. ;*  TranslateScrap
  322. ;* 
  323. ;*  This routine resizes the destination handle and fills it with data of the requested format.
  324. ;*  The data is generated by translated one or more source formats of data supplied by
  325. ;*  the procedure srcDataGetter.  
  326. ;*  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  327. ;*  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  328. ;* 
  329. ;*  Enter:    sourceDataGetter            Pointer to routine that can get src data
  330. ;*             sourceDataGetterRefCon        Extra parameter for dataGetter
  331. ;*             destinationFormat            Format of data desired
  332. ;*             destinationData                Handle in which to store translated data
  333. ;*             
  334. ;*  Exit:    dstData                        Handle is resized and filled with data in requested format
  335. ;
  336.  
  337. ;
  338. ; pascal OSErr TranslateScrap(GetScrapData sourceDataGetter, void *sourceDataGetterRefCon, ScrapType destinationFormat, Handle destinationData, short progressDialogID)
  339. ;
  340.     IF TARGET_OS_MAC ** TARGET_CPU_68K ** ¬ TARGET_RT_MAC_CFM THEN
  341.         Macro
  342.         _TranslateScrap
  343.             moveq               #14,D0
  344.             dc.w                $ABFC
  345.         EndM
  346.     ELSEIF TARGET_OS_MAC ** TARGET_RT_MAC_CFM THEN
  347.         IMPORT_CFM_FUNCTION TranslateScrap
  348.     ENDIF
  349.  
  350.  
  351.  
  352.     ENDIF ; __TRANSLATION__ 
  353.  
  354.